Skip to content

Revamp the guides section: taxonomy, single-page structure, and new landing/filter UX#25338

Draft
dvdksn wants to merge 8 commits into
docker:mainfrom
dvdksn:worktree-guides-revamp
Draft

Revamp the guides section: taxonomy, single-page structure, and new landing/filter UX#25338
dvdksn wants to merge 8 commits into
docker:mainfrom
dvdksn:worktree-guides-revamp

Conversation

@dvdksn

@dvdksn dvdksn commented Jun 12, 2026

Copy link
Copy Markdown
Contributor

What

A full revamp of the /guides section — taxonomy, structure, and UX.

Preview: https://deploy-preview-25338--docsdocker.netlify.app/guides/

Taxonomy & structure

  • Replaces the sprawling 24-tag set with a focused 9-tag taxonomy aligned to use case / SDLC: Languages & frameworks, AI, Testing, CI/CD, Security, Databases, Deployment, Admin, Hands-on labs.
  • Removes the languages taxonomy entirely (data/languages.yaml and all languages: front matter).
  • Collapses all multi-page guide series into single pages, with aliases so old sub-page URLs continue to resolve.
  • Deletes redirect-only shim pages and flattens directory-wrapped single pages.

Landing page (/guides/)

  • New landing page w/ hero, a sticky Jump to category rail with live counts, and category sections with a two-column (title / summary) list.
  • Instant text filter matching title, summary, and tags. While filtering, the rail becomes a single-column result view with a N of M guides count + Clear, and the grouped/numbered view returns when cleared.
  • Whole-row link cards with hover affordance; the page fills the viewport so a single result doesn't collapse it.

Guide content pages

  • Removes the left sidebar for the guides section (mobile drawer kept).
  • Centered reading column (92ch) with the TOC taking the remaining width.
  • Summary rendered as a lead paragraph under the h1.
  • TOC scrollbar auto-hides until hover; breadcrumbs render at a consistent size inside and outside prose.

Notes

  • Deep full-text search across guide bodies is still handled by the existing site-wide Pagefind (⌘K); the landing filter is the fast metadata-narrowing surface.
  • series.html is retained — it's still used by get-started pages.

Validation

  • Site builds clean locally (Hugo dev server, no errors / broken refs).
  • All collapsed sub-page URLs redirect via aliases.

Follow-ups

  • Prune guides that we no longer need/want
  • Tighten the guides that span too many concepts (e.g. language guides; remove cicd/deploy/sscs)

🤖 Generated with Claude Code

@netlify

netlify Bot commented Jun 12, 2026

Copy link
Copy Markdown

Deploy Preview for docsdocker ready!

Name Link
🔨 Latest commit eb68604
🔍 Latest deploy log https://app.netlify.com/projects/docsdocker/deploys/6a2bf7110f17b20008982b32
😎 Deploy Preview https://deploy-preview-25338--docsdocker.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions github-actions Bot added area/build Relates to Dockerfiles or docker build command hugo Updates related to hugo area/config area/guides labels Jun 12, 2026
dvdksn and others added 6 commits June 12, 2026 12:44
Phase 1 of the guides section revamp:

- Replace 24-tag taxonomy with 7 focused use-case/SDLC tags:
  ai, testing, cicd, security, admin, databases, deployment
- Remove language taxonomy entirely (delete data/languages.yaml,
  strip languages: front matter from all guides)
- Delete 6 redirect shim pages (dhi-from-doi, dhi-from-wolfi,
  dhi-go-example, dhi-nodejs-example, dhi-python-example,
  lab-docker-for-ai-redirect)
- Flatten 3 directory-wrapped single pages (bake, compose-bake, zscaler)
- Retag all ~100 guide pages with new taxonomy
- Move all tags: to params.tags for consistent placement
- Collapse 47 multi-page guide series into single _index.md files
  (180 sub-pages merged; headings demoted one level, sub-page
  titles become H2 sections)
- Add URL aliases for all deleted sub-pages so old URLs redirect
  to the parent guide

Phase 2 (template rewrite: tag-pill UX, remove language filter,
simplify guide cards) follows in a separate session.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Landing page (layouts/guides/landing.html):
- Remove sidebar filter (checkboxes, language buttons)
- Hero section: guide count, large "Guides." heading, description
- Sticky left "Jump to" nav with numbered categories and counts
- Sections per tag with 2-column card grid (title | summary)
- Scrollspy via IntersectionObserver highlights active section
- No Alpine.js filtering — browse by scrolling/jumping

Content pages (layouts/guides/list.html, new):
- Clean left sidebar: just mainnav, no guide-specific metadata
- Slightly wider article (max-w-5xl)
- TOC stays in right column via baseof.html default

Other:
- data/tags.yaml: add description to each tag (shown under section heading)
- layouts/_partials/guide-languages.html: deleted (languages removed in Phase 1)
- layouts/_partials/sidebar/guides.html: simplify (remove stepper, resource_links,
  languages — now just title, summary, tags, time, back link)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Tag taxonomy expanded from 7 to 9 tags:
- languages (new): 17 language/framework guides pulled from cicd
  (angular, bun, cpp, deno, dotnet, golang, java, laravel, nextjs,
   nodejs, php, python, r, reactjs, ruby, rust, vuejs)
- cicd: now pipeline/build tools only (gha, bake, azure-pipelines,
  docker-build-cloud, docker-compose, opentelemetry, etc.)
- labs (new): 12 interactive lab guides previously scattered across
  ai, security, and cicd; now grouped together at the end

Landing page tag order: languages, ai, testing, cicd, security,
databases, deployment, admin, labs

Also fixes carried over from build testing:
- Broken front matter delimiters in container-supported-development.md
  and dhi-openshift.md (resource_links[]--- → newline before ---)
- Orphaned url: lines in 16 guide files (leftover resource_links children)
- 96 broken relative links in 18 merged guide _index.md files
  (containerize.md, configure-github-actions.md etc. → ./ or anchor)
- /guides/docker-scout/sbom.md and s3c.md refs in sbom.md → /guides/docker-scout/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…rome

Guide content pages now use a clean, centered reading layout:
- Drop the 320px left sidebar for the whole guides section (baseof.html
  conditions the desktop sidebar on type != guides; mobile drawer kept)
- Remove the obsolete /guides/** -> layout: series cascade in hugo.yaml so
  collapsed guides route to guides/list.html instead of the old series layout
- New guides/single.html + updated guides/list.html: centered reading column
  (max-w-[92ch]) with the TOC taking the remaining width, justify-center so
  the pair sits balanced rather than left-heavy
- Render the guide summary as a lead paragraph under the h1 (content-default)
- aside.html: auto-hide the TOC scrollbar until hover (new scrollbar-hover
  utility)
- breadcrumbs: use an absolute font-size so they render identically inside
  prose (guide pages) and outside it (landing)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Instant client-side filter (Alpine.js) matching title, summary, and tags
  across the already-rendered guide list; multi-word queries are AND-matched
- Refined search input with inline clear button and Esc-to-clear
- While filtering: hide the jump-to rail and go single-column full-width,
  flatten the grouped sections into one list, and show a "N of M guides"
  meta bar with a Clear action
- Container fills the viewport (min-height) so a single result no longer
  collapses the page
- Whole-row link cards with hover affordance (arrow), plus a polished
  empty-results state

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Convert every directory-based guide from a branch bundle (_index.md =
  section) to a leaf bundle (index.md = single page). URLs and any
  co-located images are preserved; the guides are now kind=page, not
  sections.
- Re-collapse the Node.js guide on top of main's refresh (docker#25319): merge
  the refreshed containerize/develop/run-tests/configure-github-actions/
  secure-supply-chain/deploy topics into one page, drop the languages
  field, move tags under params ([languages]), and add aliases for the
  old /guides/nodejs/<topic>/ URLs.
- Landing: enumerate guides with RegularPagesRecursive instead of .Pages
  so every guide is listed (now that they're regular pages), including the
  nested frameworks/laravel guide that the non-recursive .Pages missed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@dvdksn dvdksn force-pushed the worktree-guides-revamp branch from ff4b077 to fe8c2af Compare June 12, 2026 10:52
dvdksn and others added 2 commits June 12, 2026 13:59
Hugo's --printUnusedTemplates (run with --panicOnWarning in CI) flagged
five templates left unused after the guides revamp. Delete them:

- _partials/guide-tags.html      tags are shown as landing sections now,
                                  not chips
- _partials/guides-stepper.html  no multi-page series remain
- _partials/sidebar/guides.html  guide pages use a mainnav-only left rail
- guides/list.html               all guides are single pages; the section
                                  root uses the landing layout
- redirect/single.html           its only users were the DHI redirect
                                  shims removed in the taxonomy pass

Also drop the now-dead type==guides branch from baseof's default left
block (it referenced the deleted sidebar/guides.html).

Verified: hugo --gc --minify --panicOnWarning --printUnusedTemplates
builds clean with no unused templates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- genai-video-bot, pre-seeding: remove stray "---" lines that a Phase 1
  front-matter delimiter fix mistakenly inserted after lines ending in
  dashes (the .env separator and a psql table rule). Those lines broke
  out of indented code fences, so markdownlint saw code as headings
  (MD022/MD023/MD025) and a dangling fence (MD040).
- cpp: repoint a stale body link from the old /guides/language/cpp/
  multistage/ path (collapsed away) to /guides/cpp/, fixing the htmltest
  broken-link error. Front-matter aliases keep the old paths intact.

Verified: markdownlint clean on both files; hugo --gc --minify
--panicOnWarning --printUnusedTemplates builds clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/build Relates to Dockerfiles or docker build command area/config area/guides hugo Updates related to hugo

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant